/**
 * Copyright 2006 gworks.com.au
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. (http://www.apache.org/licenses/LICENSE-2.0)
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed 
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for 
 * the specific language governing permissions and limitations under the License.
 *
 * <dhamma-message src="Atisha (11th century Tibetan Buddhist master)">
 * 	The greatest achievement is selflessness. The greatest worth is self-mastery.
 * 	The greatest quality is seeking to serve others. The greatest precept is continual awareness.
 * 	The greatest medicine is the emptiness of everything. The greatest action is not conforming with the worlds ways.
 * 	The greatest magic is transmuting the passions. The greatest generosity is non-attachment.
 * 	The greatest goodness is a peaceful mind. The greatest patience is humility.
 * 	The greatest effort is not concerned with results. The greatest meditation is a mind that lets go.
 * 	The greatest wisdom is seeing through appearances. 
 * </dhamma-message>
 */
package org.javaongems.client;

import java.util.Map;

/**
 * <p>Provides the common scaffolds of a controller.</p>
 * <p>Responsiblities:
 * <ul>
 * 	<li>manage the relationship between a model (ie. data representation) 
 * 			and a view (ie. visual representation)
 * 	<li>handle the events/inputs associated with the view and submit signals
 * 			to the model for maniupulation and to the view for update
 * 	<li>initiate the construction of the view and fetch the model as required
 * 	<li>destruct the view and any associated resources
 * 	<li>manage signals sent from the coordinator
 * </ul>
 * </p>
 * 
 * <p>Collaborators:
 * <ul>
 * 	<li> Coordinator - who manage the container
 * 	<li> Commands - that execute the instruction set for controllers
 * </ul>
 * </p>
 * @see org.javaongems.client.Coordinator
 * @see org.javaongems.client.Command
 * 
 * @author Ashin Wimalajeewa (ash)
 */
public interface Controller {
	/**
	 * Query the cargo associated with the controller. Cargo is convenient 
	 * storage for controller specific properties. 
	 * @return the cargo (user-defined baggage) that is pinned to the
	 * controller
	 */
	public Map getCargo();
	
	/**
	 * Query the model associated with the controller. The model is the data
	 * representation that one or more views will attempt to visualise.
	 * @return the model as an opaque object for friendly access
	 */
	public Object getModel();
	
	/**
	 * Query the view that is associated with the controller. Note, controllers 
	 * may have 0 or more views representations. When there is more than one 
	 * representation an aggregate view is created to manage signalling.
	 * @return view associated with this controller
	 */
	public View	getView();
	
	/**
	 * Command that prepares a controller for (run)ning by initialising any 
	 * dependent resources.
	 * @param config - user defined configuration submitted by the gemlet, or
	 * parent controller
	 */
	public void setUp(Map config);
	
	/**
	 * Command that executes the controller's core behaviour.
	 */
	public void run();
	
	/**
	 * Command that destructs any scaffolds and or resources that were 
	 * initialised during setUp() and run() 
	 */
	public void tearDown();
	
	/**
	 * Query issued by the coordinator as to whether the controller is in a
	 * valid state to close. This signals to the controller that a request has 
	 * been made to exit the application. Controllers should inspect their 
	 * state and determine if there is any unsaved data that must persist. If 
	 * so, then return a veto message.
	 * @return null - if no veto. non-null message to veto the closure
	 *
	 * @see Gem#onWindowClosing()
	 * @see com.google.gwt.user.client.WindowCloseListener#onWindowClosing()
	 */
	public String containerCloseRequest();
}